   This file documents GTK, the GIMP Toolkit

   Copyright (C) 1996 Peter Mattis Copyright (C) 1997 Peter Mattis

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by Peter Mattis.

The alignment widget
====================

Description
-----------

   The alignment widget is a container (see GtkContainer) derived
from the bin widget (see GtkBin). Its entire purpose is to give the
programmer flexibility in how the child it manages is positioned when a
window is resized.

   Normally, a widget is allocated at least as much size as it
requests. (see GtkContainer for a discussion of geometry
management). When a widget is allocated more size than it requests there
is a question of how the widget should expand. By convention, most GTK
widgets expand to fill their allocated space. Sometimes this behavior is
not desired. The alignment widget allows the programmer to specify how a
widget should expand and position itself to fill the area it is
allocated.

Options
-------

 - User Option: xscale
 - User Option: yscale
     The XSCALE and YSCALE options specify how to scale the child
     widget. If the scale value is 0.0, the child widget is allocated
     exactly the size it requested in that dimension. If the scale
     value is 1.0, the child widget is allocated all of the space in a
     dimension. A scale value of 1.0 for both x and y is equivalent to
     not using an alignment widget.

 - User Option: xalign
 - User Option: yalign
     The XALIGN and YALIGN options specify how to position the child
     widget when it is not allocated all the space available to it
     (because the XSCALE and/or YSCALE options are less than 1.0). If
     an alignment value is 0.0 the widget is positioned to the left (or
     top) of its allocated space. An alignment value of 1.0 positions
     the widget to the right (or bottom) of its allocated space. A
     common usage is to specify XALIGN and YALIGN to be 0.5 which
     causes the widget to be centered within its allocated area.

Signals
-------

Functions
---------

 - Function: guint gtk_alignment_get_type (void)
     Returns the `GtkAlignment' type identifier.

 - Function: GtkWidget* gtk_alignment_new (gfloat XALIGN, gfloat
          YALIGN, gfloat XSCALE, gfloat YSCALE)
     Create a new `GtkAlignment' object and initialize it with the
     values XALIGN, YALIGN, XSCALE and YSCALE. The new widget is
     returned as a pointer to a `GtkWidget' object. `NULL' is returned
     on failure.

 - Function: void gtk_alignment_set (GtkAlignment *ALIGNMENT, gfloat
          XALIGN, gfloat YALIGN, gfloat XSCALE, gfloat YSCALE)
     Set the XALIGN, YALIGN, XSCALE and YSCALE options of an alignment
     widget. It is important to not set the fields of the
     `GtkAlignment' structure directly (or, for that matter, any type
     derived from `GtkObject').

 - Function: GtkAlignment* GTK_ALIGNMENT (gpointer OBJ)
     Cast a generic pointer to `GtkAlignment*'. See Standard Macros,
     for more info.

 - Function: GtkAlignmentClass* GTK_ALIGNMENT_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkAlignmentClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_ALIGNMENT (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkAlignment' object.
     See Standard Macros, for more info.

The arrow widget
================

Description
-----------

   The arrow widget is derived from the misc widget (see GtkMisc)
and is intended for use where a directional arrow (in one of the four
cardinal directions) is desired. As such, it has very limited
functionality and basically only draws itself in a particular direction
and with a particular shadow type. The arrow widget will expand to fill
all the space it is allocated.

Options
-------

 - User Option: arrow_type
     The ARROW_TYPE option specifies which direction the arrow will
     point. It can be one of `GTK_ARROW_UP', `GTK_ARROW_DOWN',
     `GTK_ARROW_LEFT' or `GTK_ARROW_RIGHT'. This will set the arrow
     pointing in the direction specified.

 - User Option: shadow_type
     The SHADOW_TYPE option specifies how to draw the shadow for the
     arrow. Currently, only the `GTK_SHADOW_IN' and `GTK_SHADOW_OUT'
     shadow types are supported for drawing arrows. Other shadow types
     will cause nothing to be drawn.

Signals
-------

Functions
---------

 - Function: guint gtk_arrow_get_type (void)
     Returns the `GtkArrow' type identifier.

 - Function: GtkWidget* gtk_arrow_new (GtkArrowType ARROW_TYPE,
          GtkShadowType SHADOW_TYPE)
     Create a new `GtkArrow' object and initialize it with the values
     ARROW_TYPE and SHADOW_TYPE. The new widget is returned as a
     pointer to a `GtkWidget' object. `NULL' is returned on failure.

 - Function: void gtk_arrow_set (GtkArrow *ARROW, GtkArrowType
          ARROW_TYPE, GtkShadowType SHADOW_TYPE)
     Set the ARROW_TYPE and SHADOW_TYPE options of an arrow widget. It
     is important to not set the fields of the `GtkArrow' structure
     directly (or, for that matter, any type derived from `GtkObject').

 - Function: GtkArrow* GTK_ARROW (gpointer OBJ)
     Cast a generic pointer to `GtkArrow*'. See Standard Macros, for
     more info.

 - Function: GtkArrowClass* GTK_ARROW_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkArrowClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_ARROW (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkArrow' object.
     See Standard Macros, for more info.

The aspect frame widget
=======================

Description
-----------

   Ensure that the child window has a specified aspect ratio or, if
obey_child, has the same aspect ratio as its requested size.  Derived
from GtkFrame).

Options
-------

 - User Option: label

 - User Option: xalign

 - User Option: yalign

 - User Option: ratio

 - User Option: obey_child

Signals
-------

Functions
---------

 - Function: guint gtk_aspect_frame_get_type (void)
     Returns the `GtkAspectFrame' type identifier.

 - Function: GtkWidget* gtk_aspect_frame_new (gchar *LABEL, gfloat
          XALIGN, gfloat YALIGN, gfloat RATIO, gint OBEY_CHILD)
     Create a new `GtkAspectFrame' object and initialize it with the
     values LABEL, XALIGN, YALIGN, RATIO and OBEY_CHILD.  The new
     widget is returned as a pointer to a `GtkWidget' object.  `NULL'
     is returned on failure.

 - Function: void gtk_aspect_frame_set (GtkAspectFrame *ASPECT_FRAME,
          gfloat XALIGN, gfloat YALIGN, gfloat RATIO, gint OBEY_CHILD)

 - Function: GtkAspectFrame* GTK_ASPECT_FRAME (gpointer OBJ)
     Cast a generic pointer to `GtkAspectFrame*'. See Standard Macros,
     for more info.

 - Function: GtkAspectFrameClass* GTK_ASPECT_FRAME_CLASS (gpointer
          CLASS)
     Cast a generic pointer to `GtkAspectFrameClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_ASPECT_FRAME (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkAspectFrame'
     object. See Standard Macros, for more info.

The bin widget
==============

Description
-----------

   The bin widget is a container (see GtkContainer) derived from the
container widget. It is an abstract base class. That is, it is not
possible to create an actual bin widget. It exists only to provide a
base of functionality for other widgets. Specifically, the bin widget
provides a base for several other widgets that contain only a single
child. These widgets include alignments (see GtkAlignment), frames
(see GtkFrame), items (see GtkItem), viewports (see
GtkViewport) and windows (see GtkWindow)

Options
-------

Signals
-------

Functions
---------

 - Function: guint gtk_bin_get_type (void)
     Returns the `GtkBin' type identifier.

 - Function: GtkBin* GTK_BIN (gpointer OBJ)
     Cast a generic pointer to `GtkBin*'. See Standard Macros, for
     more info.

 - Function: GtkBinClass* GTK_BIN_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkBinClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_BIN (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkBin' object. See
     Standard Macros, for more info.

The box widget
==============

Description
-----------

   The box widget is a container (see GtkContainer) derived from the
container widget. It is an abstract base class used by the horizontal
box (see GtkHBox), the vertical box (see GtkVBox) and the
(see GtkButtonBox) widgets to provide a base of common
functionality.

   A box provides an abstraction for organizing the position and size of
widgets. Widgets in a box are laid out horizontally or vertically. By
using a box widget appropriately, a programmer can control how widgets
are positioned and how they will be allocated space when a window gets
resized.

   The key attribute of boxes is that they position their children in a
single row (horizontal boxes) or column (vertical boxes). In the case of
horizontal boxes, all children are stretched vertically. The vertical
size of the box is determined by the largest vertical requisition of all
of its children. Similarly, a vertical box stretches all of its children
horizontally. The horizontal size (of the vertical box) is determined by
the largest horizontal requisition of all of its children. An alignment
widget (see GtkAlignment) can be used to control child allocation
more precisely on a per child basis.

   The second attribute of boxes is how they expand children. In the
case of a horizontal box, the main control is over how children are
expanded horizontally to fill the allocated area. (The rest of this
discussion will focus on horizontal boxes but it applies to vertical
boxes as well).

   There are two flags which can be set controlling how a widget is
expanded horizontally in a horizontal box. These are the `expand' and
`fill'. There operation is fairly simple. If `expand' is set, the
child's potentially allocated area will expand to fill available space.
If `fill' is set, the child's actual allocated area will be its
potentially allocated area. There is a difference between the
potentially area (which is the area the box widget sets aside for the
child) and the actual allocated area (which is the area the box widget
actual allocates for the widget via `gtk_widget_size_allocate').

   The allocation of space to children occurs as follows (for horizontal
boxes):
  1. All children are allocated at least their requested size
     horizontally and the maximum requested child size vertically.

  2. Any child with the `expand' flag set is allocated `extra_width /
     nexpand_children' extra pixels horizontally. If the `homogeneous'
     flag was set, all children are considered to have the `expand' flag
     set. That is, all children will be allocated the same area.The
     horizontal box is a fair widget and, as such, divides up any extra
     allocated space evenly among the "expand" children. (Those children
     which have the `expand' flag set). The exception occurs when
     `extra_width / nexpand_children' does not divide cleanly. The extra
     space is given to the last widget.

  3. `spacing' number of pixels separate each child. Note: The
     separation is between the potentially allocated area for each
     child and not the actual allocated area. The `padding' value
     associated with each child causes that many pixels to be left
     empty to each side of the child.

  4. If a child has the `fill' flag set it is allocated its potentially
     allocated area. If it does not, it is allocated its requested size
     horizontally and centered within its potentially allocated area.
     Its vertical allocation is still the maximum requested size of any
     child.

  5. Children placed at the start of the box are placed in order of
     addition to the box from left to right in the boxes allocated
     area.. Children placed at the end of the box are placed in order
     of addition from right to left in the boxes allocated area.

   See GtkHBox, and GtkVBox, for code examples of using
horizontal and vertical boxes.

Options
-------

 - User Option: expand

 - User Option: fill

 - User Option: padding

 - User Option: expand

Signals
-------

Functions
---------

 - Function: guint gtk_box_get_type (void)
     Returns the `GtkBox' type identifier.

 - Function: void gtk_box_pack_start (GtkBox *BOX, GtkWidget *CHILD,
          gint EXPAND, gint FILL, gint PADDING)
     Add CHILD to the front of BOX. The flags EXPAND and FILL and the
     padding value of PADDING are associated with CHILD.

 - Function: void gtk_box_pack_end (GtkBox *BOX, GtkWidget *CHILD, gint
          EXPAND, gint FILL, gint PADDING)
     Add CHILD to the end of BOX. The flags EXPAND and FILL and the
     padding value of PADDING are associated with CHILD.

 - Function: void gtk_box_pack_start_defaults (GtkBox *BOX, GtkWidget
          *WIDGET)
     A convenience function which is equivalent to the following:

            gtk_box_pack_start (BOX, WIDGET, TRUE, TRUE, 0);

 - Function: void gtk_box_pack_end_defaults (GtkBox *BOX, GtkWidget
          *WIDGET)
     A convenience function which is equivalent to the following:

            gtk_box_pack_start (BOX, WIDGET, TRUE, TRUE, 0);

 - Function: void gtk_box_set_homogeneous (GtkBox *BOX, gint
          HOMOGENEOUS)
     Set the homogeneous setting of this box to HOMOGENEOUS.

 - Function: void gtk_box_set_spacing (GtkBox *BOX, gint SPACING)

 - Function: void gtk_box_reorder_child (GtkBox *BOX, GtkWidget *CHILD,
          guint POS)

 - Function: void gtk_box_query_child_packing (GtkBox *BOX, GtkWidget
          *CHILD, gint *EXPAND, gint *FILL, gint *PADDING, GtkPackType
          *PACK_TYPE)

 - Function: void gtk_box_set_child_packing (GtkBox *BOX, GtkWidget
          *CHILD, gint EXPAND, gint FILL, gint PADDING, GtkPackType
          *PACK_TYPE)

 - Function: GtkBox* GTK_BOX (gpointer OBJ)
     Cast a generic pointer to `GtkBox*'. See Standard Macros, for
     more info.

 - Function: GtkBoxClass* GTK_BOX_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkBoxClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_BOX (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkBox' object. See
     Standard Macros, for more info.

The button box widget
=====================

Description
-----------

   The button box widget is a container (see GtkContainer) derived
from the (see GtkBox) widget. It is an abstract base class used by
the horizontal button box (see GtkHButtonBox) and the vertical
button box (see GtkVButtonBox) widgets to provide a base of common
functionality.

   The button box, like the box widget, (see GtkBox) provides an
abstraction for organizing position and size of widgets. In the case of
the button box it is targeted at the button widget,(see GtkButton).
Button widgets are laid out in the box horizontally or vertically. By
using a button box widget appropriately, a programmer can control how
the button widgets are positioned and how they will be allocated space
when a window gets resized.

Options
-------

 - User Option: layout_style
             * `GTK_BUTTONBOX_SPREAD'

        * The layout style `GTK_BUTTONBOX_SPREAD' will spread the
          buttons out evenly within the button box. When the parent
          window is resized they will re-adjust to the new window
          dimensions. The `gtk_button_box_set_spacing' function will
          set the minimum space that the buttons will leave between
          themselves.

             * `GTK_BUTTONBOX_EDGE'

        *             * `GTK_BUTTONBOX_START'

        * The layout style `GTK_BUTTONBOX_START' will place the buttons
          at the start of the button box, taking into account the
          spacing as set by the `gtk_button_box_set_spacing' function.
          The buttons will not move when the parent window is re-sized.

             * `GTK_BUTTONBOX_END'

        * The layout style `GTK_BUTTONBOX_END' will place the buttons
          at the end of the button box, taking into account the spacing
          as set by the `gtk_button_box_set_spacing' function. Again
          like the `GTK_BUTTONBOX_START' layout style the buttons will
          not move when the parent window is re-sized.

 - User Option: width

 - User Option: height

 - User Option: ipad_x
 - User Option: ipad_y

Signals
-------

Functions
---------

 - Function: guint gtk_button_box_get_type (void)
     Returns the `GtkButtonBox' type identifier.

 - Function: void gtk_button_box_set_child_size_default (gint WIDTH,
          gintHEIGHT)

 - Function: void gtk_button_box_set_child_ipadding_default (gint
          IPAD_X, gint IPAD_Y)

 - Function: void gtk_button_box_get_child_size_default (gint *WIDTH,
          gint *HEIGHT)

 - Function: void gtk_button_box_get_child_ipadding_default (gint
          *IPAD_X, gint *IPAD_Y)

 - Function: void gtk_button_box_set_child_size (GtkButtonBox *WIDGET,
          gint WIDTH, gint HEIGHT)

 - Function: void gtk_button_box_set_child_ipadding (GtkButtonBox
          *WIDGET, gint IPAD_X, gint IPAD_Y)

 - Function: void gtk_button_box_set_layout (GtkButtonBox *WIDGET, gint
          LAYOUT_STYLE)
     This will set the layout style of the buttons within this box.
     Currently it can be set to one of `GTK_BUTTONBOX_SPREAD',
     `GTK_BUTTONBOX_EDGE', `GTK_BUTTONBOX_START' or `GTK_BUTTONBOX_END'.

     The following example:
              gtk_button_box_set_layout (GTK_BUTTON_BOX (box),
                                         GTK_BUTTONBOX_SPREAD);
     Will set the BOX argument to the "SPREAD" layout style described
     above.

 - Function: gint gtk_button_box_get_spacing (GtkButtonBox *WIDGET)
     Get the per widget value for spacing within the button box. This
     value is the amount of space that will be between the individual
     buttons contained by this box.

 - Function: void gtk_button_box_get_child_size (GtkButtonBox *WIDGET,
          gint *WIDTH, gint *HEIGHT)

 - Function: void gtk_button_box_get_child_ipadding (GtkButtonBox
          *WIDGET, gint *IPAD_X, gint *IPAD_Y)
     Get the per widget value for the padding inside the buttons. This
     value controls how large the buttons will be within the box.

 - Function: gint gtk_button_box_get_layout (GtkButtonBox *WIDGET)
     Get the LAYOUT_STYLE for the `GtkButtonBox' object passed to this
     function in the WIDGET variable.

             layout = gtk_button_box_get_layout(GTK_BUTTON_BOX (box));

 - Function: GtkButtonBox* GTK_BUTTON_BOX (gpointer OBJ)
     Cast a generic pointer to `GtkButtonBox*'. See Standard Macros,
     for more info.

 - Function: GtkButtonBoxClass* GTK_BUTTON_BOX_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkButtonBoxClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_BUTTON_BOX (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkButtonBox' object.
     See Standard Macros, for more info.

The button widget
=================

Description
-----------

   A pressable button.  Contains a widget.  Changes its appearance
(hilites) when it gets the focus.  Changes its appearance (pressed) when
activated.  Derived from GtkContainer.

Signals
-------

 - Signal: void GtkButton::pressed (GtkButton *BUTTON)

 - Signal: void GtkButton::released (GtkButton *BUTTON)

 - Signal: void GtkButton::clicked (GtkButton *BUTTON)

 - Signal: void GtkButton::enter (GtkButton *BUTTON)

 - Signal: void GtkButton::leave (GtkButton *BUTTON)

Functions
---------

 - Function: guint gtk_button_get_type (void)
     Returns the `GtkButton' type identifier.

 - Function: GtkWidget* gtk_button_new (void)
     Create a new `GtkButton' object. The new widget is returned as a
     pointer to a `GtkWidget' object. `NULL' is returned on failure.

 - Function: GtkWidget* gtk_button_new_with_label (gchar *LABEL)
     Create a new `GtkButton' object and set the text that is on the
     button to LABEL. The new widget is returned as a pointer to a
     `GtkWidget' object. `NULL' is returned on failure.

 - Function: void gtk_button_pressed (GtkButton *BUTTON)

 - Function: void gtk_button_released (GtkButton *BUTTON)

 - Function: void gtk_button_clicked (GtkButton *BUTTON)

 - Function: void gtk_button_enter (GtkButton *BUTTON)

 - Function: void gtk_button_leave (GtkButton *BUTTON)

 - Function: GtkButton* GTK_BUTTON (gpointer OBJ)
     Cast a generic pointer to `GtkButton*'. See Standard Macros,
     for more info.

 - Function: GtkButtonClass* GTK_BUTTON_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkButtonClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_BUTTON (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkButton' object.
     See Standard Macros, for more info.

The check button widget
=======================

Description
-----------

   Another form of toggle button (see GtkToggleButton) with an
indicator.  Contains a widget to the right of the indicator.  Changes
its appearance (hilites) when it gets the focus.

Options
-------

Signals
-------

Functions
---------

 - Function: guint gtk_check_button_get_type (void)
     Returns the `GtkCheckButton' type identifier.

 - Function: GtkWidget* gtk_check_button_new (void)
     Create a new `GtkCheckButton' object and initialize it with the
     default values in the library. The new widget is returned as a
     pointer to a `GtkWidget' object. A `NULL' is returned on failure.

 - Function: GtkWidget* gtk_check_button_new_with_label (gchar *LABEL)
     Create a new `GtkCheckButton' object and initialize it with the
     values LABEL. The new widget is returned as a pointer to a
     `GtkWidget' object. `NULL' is returned on any failure.

 - Function: GtkCheckButton* GTK_CHECK_BUTTON (gpointer OBJ)

 - Function: GtkCheckButtonClass* GTK_CHECK_BUTTON_CLASS (gpointer
          CLASS)

 - Function: gint GTK_IS_CHECK_BUTTON (gpointer OBJ)

 - Function: GtkCheckButton* GTK_CHECK_BUTTON (gpointer OBJ)
     Cast a generic pointer to `GtkCheckButton*'. See Standard Macros,
     for more info.

 - Function: GtkCheckButtonClass* GTK_CHECK_BUTTON_CLASS (gpointer
          CLASS)
     Cast a generic pointer to `GtkCheckButtonClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_CHECK_BUTTON (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkCheckButton'
     object. See Standard Macros, for more info.

The check menu item widget
==========================

Description
-----------

   Derived from GtkMenuItem.  Very similar to a checkbutton
(see GtkCheckButton), except that it's a menu item.  Has a toggled
state which is displayed in a small rectangle to the left of the
contained widget.

Options
-------

 - User Option: label

 - User Option: state

Signals
-------

 - Signal: void GtkCheckMenuItem::toggled (GtkCheckMenuItem
          *CHECK_MENU_ITEM)

Functions
---------

 - Function: guint gtk_check_menu_item_get_type (void)
     Returns the `GtkCheckMenuItem' type identifier.

 - Function: GtkWidget* gtk_check_menu_item_new (void)
     Create a new `GtkCheckMenuItem' object. The new widget is returned
     as a pointer to a `GtkWidget' object. `NULL' is returned on
     failure.

 - Function: GtkWidget* gtk_check_menu_item_new_with_label (gchar
          *LABEL)
     Create a new `GtkCheckMenuItem' object and initialize it with the
     values LABEL. The new widget is returned as a pointer to a
     `GtkWidget' object. `NULL' is returned on failure.

 - Function: void gtk_check_menu_item_set_state (GtkCheckMenuItem
          *CHECK_MENU_ITEM, gint STATE)

 - Function: void gtk_check_menu_item_toggled (GtkCheckMenuItem
          *CHECK_MENU_ITEM)

 - Function: GtkCheckMenuItem* GTK_CHECK_MENU_ITEM (gpointer OBJ)
     Cast a generic pointer to `GtkCheckMenuItem*'. See Standard Macros,
     for more info.

 - Function: GtkCheckMenuItemClass* GTK_CHECK_MENU_ITEM_CLASS (gpointer
          CLASS)
     Cast a generic pointer to `GtkCheckMenuItemClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_CHECK_MENU_ITEM (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkCheckMenuItem'
     object. See Standard Macros, for more info.

The compound list widget
========================

Description
-----------

   A list of rows of columns, with a title row.  You can insert rows,
and delete rows.  The user can scroll around and select a row.  Derived
from GtkContainer.  Cells can be empty, have a text and/or
pixmap, or be a widget.

Options
-------

Signals
-------

Functions
---------

 - Function: guint gtk_clist_get_type (void)
     Returns the `GtkCList' type identifier.

 - Function: GtkWidget* gtk_clist_new (int COLUMNS)
     Create a new `GtkCList' initializing it with the value COLUMNS.
     The new widget is returned as a pointer to a `GtkWidget' object.
     `NULL' is returned on failure.

 - Function: GtkWidget* gtk_clist_new_with_titles (int COLUMNS, gchar
          *TITLES[])

 - Function: void gtk_clist_set_border (GtkCList *CLIST, GtkShadowType
          BORDER)
     Set the border style of the CLIST to the shadow type BORDER.

 - Function: void gtk_clist_set_selection_mode (GtkCList *CLIST
          GtkSelectionMode MODE)
     Set the selection mode on the CLIST to the MODE selection mode.

 - Function: void gtk_clist_set_policy (GtkCList *CLIST, GtkPolicyType
          VSCROLLBAR_POLICY, GtkPolicyType HSCROLLBAR_POLICY)
     Set the policy on the scrollbars on the CLIST to VSCROLLBAR_POLICY
     and HSCROLLBAR_POLICY.

 - Function: void gtk_clist_freeze (GtkCList *CLIST)
     Stop all visual updates of the CLIST. Useful for when making a
     large number of changes to a `GtkCList'.

 - Function: void gtk_clist_thaw (GtkCList *CLIST)
     Allow all visual updates of the CLIST to resume.

 - Function: void gtk_clist_column_titles_show (GtkCList *CLIST)
     Show the column title buttons on the CLIST.

 - Function: void gtk_clist_column_titles_hide (GtkCList *CLIST)
     Hide the column title buttons on the CLIST.

 - Function: void gtk_clist_set_column_title (GtkCList *CLIST, gint
          COLUMN, gchar *TITLE)
     Set the title in column COLUMN of the CLIST button to TITLE.

 - Function: void gtk_clist_set_column_widget (GtkCList *CLIST, gint
          COLUMN, GtkWidget *WIDGET)
     Set the WIDGET instead of the title button for the column COLUMN
     in the CLIST.

 - Function: void gtk_clist_set_column_justification (GtkCList *CLIST,
          gint COLUMN, GtkJustification JUSTIFICATION)
     Set the COLUMN's justification, in the CLIST to JUSTIFICATION.

 - Function: void gtk_clist_set_column_width (GtkCList *CLIST, gint
          COLUMN, gint WIDTH)
     Set the pixel width of column COLUMN in the `GtkCList' CLIST to
     WIDTH. This function is a necessary step in creating a `GtkCList'
     because otherwise the column width is chosen from the width of the
     column title, which is almost never correct.

 - Function: void gtk_clist_set_row_height (GtkCList *CLIST, gint
          HEIGHT)
     Change the height of the rows in the CLIST to HEIGHT. The default
     is the height of the current font.

 - Function: void gtk_clist_moveto (GtkCList *CLIST, gint ROW,
          gintCOLUMN, gfloat ROW_ALIGN, gfloat COL_ALIGN)
     Scroll the viewing area of the `GtkClist' in CLIST to COLUMN and
     ROW. The ROW_ALIGN and COL_ALIGN are between zero and one,
     representing the location the row should appear on screen. Setting
     ROW_ALIGN or the COL_ALIGN to 0.0 will be the top or left of the
     viewing area. Setting the ROW_ALIGN or COL_ALIGN to 1.0 will be
     the bottom or right of the viewing area. If the ROW or COLUMN is
     -1 then there is no change.

 - Function: void gtk_clist_set_text (GtkCList *CLIST, gint ROW, gint
          COLUMN, gchar *TEXT)
     Set a given cell's text, located by the ROW and COLUMN, to TEXT
     replacing its current contents.

 - Function: void gtk_clist_set_pixmap (GtkCList *CLIST, gint ROW, gint
          COLUMN, GdkPixmap *PIXMAP, GdkBitmap *MASK)
     Set a given cell's text, located by the COLUMN and ROW arguments,
     to the pixmap described by the PIXMAP argument using the MASK as
     its mask. The current contents of the cell will be replaced.

 - Function: void gtk_clist_setpixtext (GtkCList *CLIST, gint ROW, gint
          COLUMN, gchar *TEXT, guint8 SPACING, GdkPixmap *PIXMAP,
          GdkBitmap *MASK)
     Set a given cell's text and pixmap, located by the ROW and COLUMN
     arguments, to the text and pixmap described by the PIXMAP and TEXT
     arguments. The MASK will be used for the pixmap mask and the
     SPACING argument specifies the spacing between the two.

 - Function: void gtk_clist_set_foreground (GtkCList *CLIST, gint ROW,
          GdkColor *COLOR)
     Set the foreground color of row ROW to COLOR in the `GtkCList'
     CLIST. The COLOR must already be allocated.

 - Function: void gtk_clist_set_background (GtkCList *CLIST, gint ROW,
          GdkColor *COLOR)
     Set the background color of row ROW to COLOR in the `GtkCList'
     pointed to by CLIST. The color must be previously allocated.

 - Function: void gtk_clist_set_shift (GtkCList *CLIST, gint ROW, gint
          COLUMN, gint VERTICAL, gint HORIZONTAL)
     Set the horizontal and vertical shift for drawing the contents of
     the cell located at ROW and COLUMN. The VERTICAL and HORIZONTAL
     arguments can be positive or negative.

 - Function: gint gtk_clist_append (GtkCList *CLIST, gchar *TEXT[])
     Append the given text, in the TEXT[] argument,  to the `GtkCList'
     pointed to by the CLIST. The return value is the index of the row
     that was just added.

 - Function: void gtk_clist_insert (GtkCList *CLIST, gint ROW, gchar
          *TEXT[])
     Insert a row into the `GtkCList' pointed to by CLIST at row ROW
     with the text in TEXT[].

 - Function: void gtk_clist_remove (GtkCList *CLIST, gint ROW)
     Remove row index ROW from the CLIST.

 - Function: void gtk_clist_set_row_data (GtkCList *CLIST, gint ROW,
          gpointer DATA)
     Will set an arbitrary data pointer, DATA, for row ROW in the
     `GtkCList' pointed to by CLIST.

 - Function: gpointer gtk_clist_get_row_data (GtkCList *CLIST, gint ROW)
     Return the data that was set for row ROW from the `GtkCList'
     pointed to by CLIST. `NULL' is returned if no data was set.

 - Function: void gtk_clist_select_row (GtkCList *CLIST, gint ROW, gint
          COLUMN)
     Force selection of a row, located by ROW and COLUMN, in the
     `GtkCList' pointed to by CLIST.

 - Function: void gtk_clist_unselect_row (GtkCList *CLIST, gint ROW,
          gint COLUMN)
     Force the unselection of a row, located by ROW and COLUMN, in the
     `GtkCList' pointed to by CLIST.

 - Function: void gtk_clist_clear (GtkCList *CLIST)
     Clear the entire contents of the `GtkCList' pointed to by CLIST.
     This is much faster then removing each item separately with
     `gtk_clist_remove'.

 - Function: GtkCList* GTK_CLIST (gpointer OBJ)
     Cast a generic pointer to `GtkCList*'. See Standard Macros, for
     more info.

 - Function: GtkCListClass* GTK_CLIST_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkCListClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_CLIST (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkCList' object.
     See Standard Macros, for more info.

The color selector widget
=========================

Description
-----------

   A widget that allows a user to pick a color in one of many ways.
They can click on a color wheel or saturation bar.  They can change hue,
saturation, value, red, green, or blue with a slider, or by entering
values.  Also allows the user to set an alpha (opacity) value.  Derived
from GtkVBox.

Options
-------

 - User Option: policy
        * GTK_UPDATE_CONTINUOUS

        * GTK_UPDATE_DISCONTINUOUS

        * GTK_UPDATE_DELAYED

 - User Option: color

 - User Option: use_opacity

 - User Option: title

Signals
-------

Functions
---------

 - Function: guint gtk_color_selection_get_type (void)
     Returns the `GtkColorSelection' type identifier.

 - Function: GtkWidget* gtk_color_selection_new (void)
     Create a new `GtkColorSelection' object. The new object is
     returned as a pointer to a `GtkWidget' object. `NULL' is returned
     on failure.

 - Function: void gtk_color_selection_set_update_policy
          (GtkColorSelection *COLORSEL, GtkUpdateType POLICY)

 - Function: void gtk_color_selection_set_color (GtkColorSelection
          *COLORSEL, gdouble *COLOR)

 - Function: void gtk_color_selection_get_color (GtkColorSelection
          *COLORSEL, gdouble *COLOR)

 - Function: void gtk_color_selection_set_opacity (GtkColorSelection
          *COLORSEL, gint USE_OPACITY)

 - Function: guint gtk_color_selection_dialog_get_type (void)
     Returns the `GtkColorSelection' type identifier.

 - Function: GtkWidget* gtk_color_selection_dialog_new (gchar *TITLE)
     Create a new `GtkColorSelection' object initializing the title bar
     of the resulting dialog to TITLE. The new widget is returned as a
     pointer to a `GtkWidget' object. `NULL' is returned on failure.

 - Function: GtkColorSelection* GTK_COLOR_SELECTION (gpointer OBJ)
     Cast a generic pointer to `GtkColorSelection*'. See Standard Macros,
     for more info.

 - Function: GtkColorSelectionClass* GTK_COLOR_SELECTION_CLASS
          (gpointer CLASS)
     Cast a generic pointer to `GtkColorSelectionClass*'. See
     Standard Macros, for more info.

 - Function: gint GTK_IS_COLOR_SELECTION (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkColorSelection'
     object. See Standard Macros, for more info.

The combo widget
================

Description
-----------

   Text input box which also lets you choose from pre-defined values
from a drop-down menu.  Derived from GtkHBox.

Options
-------

Signals
-------

Functions
---------

 - Function: guint gtk_combo_get_type (void)
     Returns the `GtkCombo' type identifier.

 - Function: GtkWidget* gtk_combo_new (void)
     Create a new `GtkCombo' object returning the new widget as a
     pointer to a `GtkWidget' object. `NULL' is returned on failure.

 - Function: void gtk_combo_set_value_in_list (GtkCombo *COMBO, gint
          VAL, gint OK_IF_EMPTY)

 - Function: void gtk_combo_set_use_arrows (GtkCombo *COMBO, gint VAL)

 - Function: void gtk_combo_set_use_arrows_always (GtkCombo *COMBO,
          gint VAL)

 - Function: void gtk_combo_set_case_sensitive (GtkCombo *COMBO, gint
          VAL)

 - Function: void gtk_combo_set_item_string (GtkCombo *COMBO, GtkItem
          *ITEM, gchar *ITEM_VALUE)

 - Function: void gtk_combo_set_popdown_strings (GtkCombo *COMBO, GList
          *STRINGS)

 - Function: GtkCombo* GTK_COMBO (gpointer OBJ)
     Cast a generic pointer to `GtkCombo*'. See Standard Macros, for
     more info.

 - Function: GtkComboClass* GTK_COMBO_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkComboClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_COMBO (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkCombo' object.
     See Standard Macros, for more info.

The container widget
====================

Description
-----------

   A base class for objects that are built out of other widgets.  Many
widgets are containers.  For example, a button contains a widget.  That
widget might be a text label (usually is), or a pixmap, or even an hbox
which has a label and a pixmap.

Options
-------

 - User Option: border_width

Signals
-------

 - Signal: void GtkContainer::add (GtkContainer *CONTAINER, GtkWidget
          *WIDGET)

 - Signal: void GtkContainer::remove (GtkContainer *CONTAINER,
          GtkWidget *WIDGET)

 - Signal: void GtkContainer::need_resize (GtkContainer *CONTAINER,
          GtkWidget *WIDGET)

 - Signal: void GtkContainer::foreach (GtkContainer *CONTAINER,
          GtkCallback CALLBACK, gpointer CALLBACK_DATA)

 - Signal: gint GtkContainer::focus (GtkContainer *CONTAINER,
          GtkDirectionType DIRECTION)

Functions
---------

 - Function: guint gtk_container_get_type (void)
     Returns the `GtkContainer' type identifier.

 - Function: void gtk_container_border_width (GtkContainer *CONTAINER,
          gint BORDER_WIDTH)

 - Function: void gtk_container_add (GtkContainer *CONTAINER, GtkWidget
          *WIDGET)
     Add WIDGET to the CONTAINER.

 - Function: void gtk_container_remove (GtkContainer *CONTAINER,
          GtkWidget *WIDGET)
     Remove WIDGET from CONTAINER.

 - Function: void gtk_container_disable_resize (GtkContainer *CONTAINER)

 - Function: void gtk_container_enable_resize (GtkContainer *CONTAINER)

 - Function: void gtk_container_block_resize (GtkContainer *CONTAINER)

 - Function: void gtk_container_unblock_resize (GtkContainer *CONTAINER)

 - Function: gint gtk_container_need_resize (GtkContainer *CONTAINER,
          GtkWidget *WIDGET)

 - Function: void gtk_container_check_resize (GtkContainer *CONTAINER,
          GtkWidget *WIDGET)

 - Function: void gtk_container_foreach (GtkContainer *CONTAINER,
          GtkCallback CALLBACK, gpointer CALLBACK_DATA)

 - Function: void gtk_container_focus (GtkContainer *CONTAINER,
          GtkDirectionType DIRECTION)

 - Function: GList* gtk_container_children (GtkContainer CONTAINER)

 - Function: GtkContainer* GTK_CONTAINER (gpointer OBJ)
     Cast a generic pointer to `GtkContainer*'. See Standard Macros,
     for more info.

 - Function: GtkContainerClass* GTK_CONTAINER_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkContainerClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_CONTAINER (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkContainer' object.
     See Standard Macros, for more info.

The multi-column tree widget
============================

Description
-----------

   The GtkCTree widget is a multi-columned list with a designated
column, the `tree column', to display hierarchically-organized data.
Each node is either a folder (a branch of the tree) or a leaf. Nodes
can be (recursively) expanded, collapsed, (un)selected, removed, moved,
sorted etc.

   GtkCTree is a descendant of GtkCList. Therefore, a cell in a
column other than the tree column can only contain a string, a pixmap,
both or nothing. A node in the tree column can contain a string and up
to two pixmaps and masks, indicating the "folder openend" and "folder
closed" status.

   Compared to GtkCList, there is no concept of row numbers. Therefore,
a number of GtkCList methods had to be re-implemented taking `GList
*node' arguments instead of `gint row'.

Options
-------

Signals
-------

 - Signal: void GtkCTree::tree_expand (GtkCTree *CTREE, GList *NODE)

 - Signal: void GtkCTree::tree_collapse (GtkCTree *CTREE, GList *NODE)

 - Signal: void GtkCTree::tree_move (GtkCTree *CTREE, GList *NODE,
          GList *NEW_PARENT, GList *NEW_SIBLING)

 - Signal: void GtkCTree::tree_select_row (GtkCTree *CTREE, GList *ROW,
          gint COLUMN)

 - Signal: void GtkCTree::tree_unselect_row (GtkCTree *CTREE, GList
          *ROW, gint COLUMN)

Functions
---------

 - Function: GtkType gtk_ctree_get_type (void)
     Returns the `GtkCTree' type identifier.

 - Function: GtkWidget* gtk_ctree_new (gint COLUMNS, gint TREE_COLUMN)
     Creates a new GtkCTree widget with the given number of columns and
     the given tree column.

     On success, a pointer to the newly created widget is returned, and
     `NULL' otherwise.

 - Function: GtkWidget* gtk_ctree_new_with_titles (gint COLUMNS, gint
          TREE_COLUMN, gchar *TITLES[])
     Creates a new GtkCTree widget with the given number of columns and
     the given tree column. The column titles are initialized to the
     strings of the array TITLES.

     On success, a pointer to the newly created widget is returned, and
     `NULL' otherwise.

 - Function: GList* gtk_ctree_insert (GtkCTree *CTREE, GList *PARENT,
          GList *SIBLING, gchar *TEXT[], guint8 SPACING, GdkPixmap
          *PIXMAP_CLOSED, GdkPixmap *MASK_CLOSED, GdkPixmap
          *PIXMAP_OPENED, GdkPixmap *MASK_OPENED, gboolean IS_LEAF,
          gboolean EXPANDED)
     Inserts a new node at the given position. If PARENT == NULL, the
     node is inserted at root level. If SIBLING == NULL, the node is
     appended to the existing list of siblings. Otherwise, the node is
     inserted before SIBLING.  If not NULL, the two pixmaps/masks are
     used to indicate the opened/closed status of the node. SPACING is
     the number of pixels between pixmap and text.  If IS_LEAF == TRUE,
     the node cannot have any children.  The initial expanded/collapsed
     status is given by EXPANDED.

     On success, the pointer to the newly inserted node is returned,
     and NULL otherwise.

 - Function: void gtk_ctree_remove (GtkCTree *CTREE, GList *NODE)
     Removes the given node and all its children.

 - Function: void gtk_ctree_clear (GtkCTree *CTREE)
     Removes all nodes of CTREE.

 - Function: void gtk_ctree_post_recursive (GtkCTree *CTREE, GList
          *NODE, GtkCTreeFunc FUNC, gpointer DATA)
     Apply FUNC to NODE and all its children, traversing CTREE in
     post-order.

 - Function: void gtk_ctree_pre_recursive (GtkCTree *CTREE, GList
          *NODE, GtkCTreeFunc FUNC, gpointer DATA)
     Apply FUNC to NODE and all its children, traversing CTREE in
     pre-order.

 - Function: gboolean gtk_ctree_is_visible (GtkCTree *CTREE, GList
          *NODE)
     Returns the visibility status of the given node. A node is said to
     be visible if in the chain of parent nodes every node is expanded.
     Or : the node is currently being displayed (but not necessarily
     inside the viewing area).

 - Function: GtkCTree* GTK_CTREE (gpointer OBJ)
     Cast a generic pointer to `GtkCTree*'. See Standard Macros, for
     more info.

 - Function: GtkCTreeClass* GTK_CTREE_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkCTreeClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_CTREE (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkCTree' object.
     See Standard Macros, for more info.

The curve widget
================

Description
-----------

   Derived from GtkDrawingArea.

Options
-------

 - User Option: type
        * GTK_CURVE_TYPE_LINEAR

        * GTK_CURVE_TYPE_SPLINE

        * GTK_CURVE_TYPE_FREE

Signals
-------

Functions
---------

 - Function: guint gtk_curve_get_type (void)
     Returns the `GtkCurve' type identifier.

 - Function: GtkWidget* gtk_curve_new (void)
     Create a new `GtkCurve' returning the new widget as a pointer to a
     `GtkWidget' object.

 - Function: void gtk_curve_reset (GtkCurve *CURVE)

 - Function: void gtk_curve_set_gamma (GtkCurve *CURVE, gfloat GAMMA)

 - Function: void gtk_curve_set_range (GtkCurve *CURVE, gfloat MIN_X,
          gfloat MAX_X, gfloat MIN_Y, gfloat MAX_Y)

 - Function: void gtk_curve_get_vector (GtkCurve *CURVE, int VECLEN,
          gfloat VECTOR[])

 - Function: void gtk_curve_set_vector (GtkCurve *CURVE, int VECLEN,
          gfloat VECTOR[])

 - Function: void gtk_curve_set_curve_type (GtkCurve *CURVE,
          GtkCurveType TYPE)

 - Function: GtkCurve* GTK_CURVE (gpointer OBJ)
     Cast a generic pointer to `GtkCurve*'. See Standard Macros, for
     more info.

 - Function: GtkCurveClass* GTK_CURVE_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkCurveClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_CURVE (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkCurve' object.
     See Standard Macros, for more info.

The gamma curve widget
======================

Description
-----------

   Lets the user edit a gamma curve (a one-to-one mapping usually used
to adjust the intensity of an image to the physical characteristics of
the output device).  You can set the minimum and maximum values for
input and output.  You can set the initial vector as well.  You are
guaranteed that every input value will have a (not necessarily unique)
output value specified.  Derived from GtkVBox.  Makes use of
GtkCurve to draw the curve.

Options
-------

Signals
-------

Functions
---------

 - Function: guint gtk_gamma_curve_get_type (void)
     Returns the `GtkGamma' type identifier.

 - Function: GtkWidget* gtk_gamma_curve_new (void)
     Create a new `GtkGamma' returning the new widget as a pointer to a
     `GtkWidget' object.

 - Function: GtkGammaCurve* GTK_GAMMACURVE (gpointer OBJ)
     Cast a generic pointer to `GtkGammaCurve*'. See Standard Macros,
     for more info.

 - Function: GtkGammaCurveClass* GTK_GAMMACURVE_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkGammaCurveClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_GAMMACURVE (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkGammaCurve' object.
     See Standard Macros, for more info.

The dialog widget
=================

Description
-----------

   The dialog widget is a window (see GtkWindow) that has a
vertical box (see GtkVBox), a horizontal box (see GtkHBox),
separated with a horizontal separator (see GtkHSeparator).

Options
-------

Signals
-------

Functions
---------

 - Function: guint gtk_dialog_get_type (void)
     Returns the `GtkDialog' type identifier.

 - Function: GtkWidget* gtk_dialog_new (void)
     Create a new `GtkDialog' object and return the new widget as a
     pointer to a `GtkWidget' object. `NULL' is returned on failure.

 - Function: GtkDialog* GTK_DIALOG (gpointer OBJ)
     Cast a generic pointer to `GtkDialog*'. See Standard Macros,
     for more info.

 - Function: GtkDialogClass* GTK_DIALOG_CLASS (gpointer CLASS)
     Cast a generic pointer to `GtkDialogClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_DIALOG (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkDialog' object.
     See Standard Macros, for more info.

The drawing area widget
=======================

Description
-----------

   A base class for widgets that need a box to draw into.  So far, only
used by GtkCurve.

Options
-------

 - User Option: width

 - User Option: height

Signals
-------

Functions
---------

 - Function: guint gtk_drawing_area_get_type (void)
     Returns the `GtkDrawingArea' type identifier.

 - Function: GtkWidget* gtk_drawing_area_new (void)
     Create a new `GtkDrawingArea' object returning the new widget as a
     pointer to a `GtkWidget' object. `NULL' is returned on failure.

 - Function: void gtk_drawing_area_size (GtkDrawingArea *DAREA, gint
          WIDTH, gint HEIGHT)
     Set the size of the DAREA widget, created previously, to WIDTH and
     HEIGHT.

 - Function: GtkDrawingArea* GTK_DRAWING_AREA (gpointer OBJ)
     Cast a generic pointer to `GtkDrawingArea*'. See Standard Macros,
     for more info.

 - Function: GtkDrawingAreaClass* GTK_DRAWING_AREA_CLASS (gpointer
          CLASS)
     Cast a generic pointer to `GtkDrawingAreaClass*'. See Standard Macros,
     for more info.

 - Function: gint GTK_IS_DRAWING_AREA (gpointer OBJ)
     Determine if a generic pointer refers to a `GtkDrawingArea'
     object. See Standard Macros, for more info.